Merging this PR will degrade performance by 10.68%

❌ 3 regressed benchmarks
✅ 239 untouched benchmarks

Performance Changes

_{Comparing rodrigobnogueira:feat/to-dict (08e8338) with master (41c1b91)}

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.86%. Comparing base (2aed5c2) to head (6a1e16f).

@@           Coverage Diff            @@
##           master    #1288    +/-   ##
========================================
  Coverage   99.86%   99.86%            
========================================
  Files          28       30     +2     
  Lines        3627     3729   +102     
  Branches      265      270     +5     
========================================
+ Hits         3622     3724   +102     
  Misses          3        3            
  Partials        2        2            

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

About the Coveralls Coverage Metrics
Coveralls report shows "40.44% coverage on new lines". Coveralls is reporting MyPy type precision coverage, not pytest test execution coverage.

"""Benchmark comparing C vs Python implementation of to_dict()."""

import timeit
import gc
from multidict._multidict import MultiDict as CMultiDict
from multidict._multidict_py import MultiDict as PyMultiDict


def create_multidict(cls, num_keys: int, vals_per_key: int):
    items = [(f"key{i % num_keys}", f"value{i}") for i in range(num_keys * vals_per_key)]
    return cls(items)


def benchmark_to_dict(md, iterations: int = 1000) -> float:
    # Disable GC during timing to reduce noise
    gc_old = gc.isenabled()
    gc.disable()
    try:
        def run():
            md.to_dict()
        return timeit.timeit(run, number=iterations)
    finally:
        if gc_old:
            gc.enable()


def run_benchmark(num_keys: int, vals_per_key: int, iterations: int = 1000) -> None:
    total_items = num_keys * vals_per_key
    c_md = create_multidict(CMultiDict, num_keys, vals_per_key)
    py_md = create_multidict(PyMultiDict, num_keys, vals_per_key)
    
    c_time = benchmark_to_dict(c_md, iterations)
    py_time = benchmark_to_dict(py_md, iterations)
    
    speedup = py_time / c_time if c_time > 0 else 0
    
    print(f"| {num_keys:>6} | {vals_per_key:>6} | {total_items:>7} | {c_time*1000:>10.2f} | {py_time*1000:>10.2f} | {speedup:>7.2f}x |")


def main() -> None:
    print("\n" + "=" * 80)
    print("to_dict() Benchmark: C Extension vs Pure Python")
    print("=" * 80)
    print(f"\n{'Iterations per test:':30} 1000")
    print(f"{'Time unit:':30} milliseconds (total for 1000 calls)\n")
    
    print("|  Keys  | V/Key  |  Total  |   C (ms)   |   Py (ms)  | Speedup |")
    print("|--------|--------|---------|------------|------------|---------|")
    
    scenarios = [
        (10, 1),
        (10, 10),
        (100, 10),
        (1000, 10),
        (100, 100),
        # Larger datasets to target >2s execution time for Python
        (2000, 20),   # 40,000 items
        (5000, 10),   # 50,000 items
    ]
    
    for num_keys, vals_per_key in scenarios:
        run_benchmark(num_keys, vals_per_key)
    
    print("\n" + "=" * 80)
    print("Speedup = Python time / C time (higher is better for C)")
    print("=" * 80 + "\n")


if __name__ == "__main__":
    main()

to_dict() Benchmark: C Extension vs Pure Python

Iterations per test: 1000
Time unit: milliseconds (total for 1000 calls)

=====================================
Speedup = Python time / C time (higher is better for C)

Hello @Vizonex ,

I've posted about using getall in this comment: #783 (comment)

I haven't look into the getall details yet, but it's not viable to use it as-is in the to_dict() transformation:
I couldn't even run the most demanding cases of the benchmark I posted in a previous message.

Using the getall function we get:

================================================================================
to_dict() Benchmark: C Extension vs Pure Python

Iterations per test: 1000
Time unit: milliseconds (total for 1000 calls)

================================================================================
Speedup = Python time / C time (higher is better for C)

@rodrigobnogueira note that there's no need to use conventional commit prefixes as they only eat up space. Towncrier uses change note-based identifiers in file names.

@rodrigobnogueira Do you think anything here could be pulled into aio-libs/aiohttp#7679?

@rodrigobnogueira Do you think anything here could be pulled into aio-libs/aiohttp#7679?

I'm guessing probably not, as it produces a list, rather than a concatenated string. I wonder how useful this feature will actually be (i.e. a user could just use a dict of lists in the first place if that's what they want...).

@rodrigobnogueira Do you think anything here could be pulled into aio-libs/aiohttp#7679?

I'm guessing probably not, as it produces a list, rather than a concatenated string. I wonder how useful this feature will actually be (i.e. a user could just use a dict of lists in the first place if that's what they want...).

I opened this PR a few months ago to address the 2022 issue requesting this feature. If this isn't the direction we want to take, I’m fine with closing it alongside #783 to avoid adding unnecessary complexity to the library.

The value of this feature is probably a more performant to_dict method, that doesn't use the self.getall described in the issue.

If this isn't the direction we want to take, I’m fine with closing it alongside #783 to avoid adding unnecessary complexity to the library.

I don't have a strong opinion, though it'd be nice to know if this is a somewhat common usecase for people. I'll let someone else decide if this is a good idea or not.

If this isn't the direction we want to take, I’m fine with closing it alongside #783 to avoid adding unnecessary complexity to the library.

I don't have a strong opinion, though it'd be nice to know if this is a somewhat common usecase for people. I'll let someone else decide if this is a good idea or not.

@Dreamsorcerer I think it would be good for libraries such as msgspec to have this feature implemented. I could see some use-cases such as sterilizing header files for debugging an http request for instance or for other configuration systems.

If this isn't the direction we want to take, I’m fine with closing it alongside #783 to avoid adding unnecessary complexity to the library.

I don't have a strong opinion, though it'd be nice to know if this is a somewhat common usecase for people. I'll let someone else decide if this is a good idea or not.

@Dreamsorcerer I think it would be good for libraries such as msgspec to have this feature implemented. I could see some use-cases such as sterilizing header files for debugging an http request for instance or for other configuration systems.

Use-case evidence, since that was the open question: this mirrors an established convenience on multidict-shaped types. Werkzeug's MultiDict has exactly this as to_dict(flat=False), and Django's QueryDict exposes it through .lists().
The request in #783 came from the litestar author, and the typical situation is not one where the user could have started with a dict of lists: the multidict arrives from a library, parsed headers or query strings, and needs exporting for JSON, test comparison, or msgspec/pydantic input, as @Vizonex mentioned. The C implementation also beats the naive getall() comprehension by a wide margin (benchmarks above).

Meanwhile all review notes are addressed, to_dict() is now documented in the API reference, and the full suite is green on 3.12 and 3.13t.